/*
    Copyright 2009 Barnet Wagman

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 */

package ot;

import java.io.*;
import java.util.*;

/** An instance of <tt>Ot</tt> is used to access objects in a particular
 *  {@link Context} (i.e. we usually use one <tt>Ot</tt> per context).
 *  Each instance of <tt>Ot</tt> has a {@link Serializer} (specified in
 *  the <tt>Ot</tt>'s constructor) that determines the details of serialization.  E.g.
 *  {@link GzipSerializer} compresses objects before storing them.
 *
 *
 * @author Barnet Wagman
 */
public interface Ot {

    public void setContext(Context c) 
        throws OtException, NoSuchContextException;
    
    public Context getContext();

    public Serializer getDefaultSerializer();

        /** Tests whether an object with <tt>path</tt> exists.
         *
         * @param path
         * @return
         * @throws ot.OtException
         */
    public boolean has(OPath path) throws OtException;

         /** Adds an object.  If an object with <tt>path</tt> already
          *  exists, it is replaced by <tt>obj</tt>.
          *  This method is equivalent to
          *  {@link #add(ot.OPath, java.io.Serializable, boolean) }
          *  with parameter <tt>replaceExtant == true</tt>.
          *
          * @param path
          * @param obj
          * @throws ot.OtException
          */
    public void add(OPath path,Serializable obj) throws OtException;

         /** Adds an object.
          *
          * @param path
          * @param obj
          * @param replaceExtant if <tt>true</tt>, an existing object will be
          *     <tt>path</tt> is replace. If <tt>false</tt> and
          *     there is an existing object with <tt>path</tt>,
          *     an {@link ObjectExistsException} is thrown.
          *
          * @throws ot.OtException
          * @throws ot.ObjectExistsException if <tt>replaceExtant == false</tt>
          *     and an objet with the specified path already exists.
          */
    public void add(OPath path, Serializable obj, boolean replaceExtant)
        throws OtException, ObjectExistsException;        

    /** Gets the object with the specified {@link Path}.
     *
     * @param path
     * @return the object with <tt>path</tt> or <tt>null</tt> if no
     *      such object exists.
     * @throws ot.OtException
     */
    public Serializable get(OPath path) throws OtException;

        /** Gets the object with the specified {@link LocO}.
         *
         * @param loc
         * @return
         * @throws ot.OtException
         */
    public Serializable get(LocO loc) throws OtException;

        /** Gets objects specified by <tt>locs</tt>.
         *
         *  @param locs only <tt>LocO</tt>s are used to retrieve
         *      objects.  <tt>LocD</tt>s are ignored.
         *  @return a <tt>List</tt> of objects or an empty list if no
         *      objects matching <tt>locs</tt> are found.
         */
    public List<Serializable> get(List<Loc> locs) throws OtException;

        /** If an implementation uses a cache, this method returns
         *  a cached object or null if the object is not cached.  If
         *  caching is not supported, this method is identical to
         *  {@link #get(ot.OPath) }.
          *
          * @param path
          * @return
          */
    public Serializable getCached(OPath path);

        /** Deletes the object with the specified path.
         *
         * @param path
         * @throws ot.OtException
         */
    public void delete(OPath path) throws OtException;


        /** Gets a list of <i>all</i> objects in the {@link Context}.
         *        
         * @return
         */
    public List<LocO> listContext() throws OtException;

        /** Gets a list objects and directories in <tt>dir</tt>. This
         *  method does <i>not</i> descend the tree.
         *
         * @param dir the <tt>DPath</tt> of a directory.  If
         *      <tt>dir == null</tt> this method returns the
         *      <tt>Loc</tt>s of the top level directory in the context.
         * @return
         */
    public List<Loc> list(DPath dir) throws OtException;

        /** Gets a list of everything (objects and directories) in a tree,
         *  starting with the contents of the specified directory.
         *
         * @param dir the <tt>DPath</tt> of a directory.  If
         *      <tt>dir == null</tt> this method returns the
         *      <tt>Loc</tt>s of objects and directories in the top level
         *      directory in the context.
         * @return
         */
    public List<Loc> listTree(DPath dir) throws OtException;
}
